home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 5 / BBS in a Box -Volume V (BBS in a Box) (April 1992).iso / Files / Prog / U-Z / XCMDSHEL.CPT / ReadMe < prev    next >
Encoding:
Text File  |  1991-10-22  |  3.8 KB  |  90 lines  |  [TEXT/ttxt]
  1. /*
  2.   © 1991 Dick Guertin
  3. */
  4.  
  5. This is a text file describing how to build an XCMD using THINK-C.
  6. Enclosed are several header.h files and source.c files that comprise
  7. a working example of the Dialog XCMD described in Chapter 3 of "XCMD's
  8. for HyperCard" by Gary Bond (MIS: Press; ISBN 0-943518-85-7).  The 29
  9. "glue" routines are in the XCmdGlue.c file.  The XCmdBlock is defined
  10. in the HyperXCmd.h file, along with prototypes for all the "glue" code.
  11.  
  12. The XCmdUtil.h and XCmdUtil.c files contain the commonly used routines,
  13. both from the Dialog XCMD example, and the examples in Chapter 6.
  14. These include the following:
  15.  
  16. short       GetParamCount (XCmdBlockPtr, short min, short max);
  17. short       CheckParamCount (XCmdBlockPtr, short amount);
  18. void        Fail (XCmdBlockPtr, char*);
  19. Handle      CopyStrToHand (char*);
  20. long        HandleToNum (XCmdBlockPtr, Handle);
  21. void        HandleToPstr (Str255, Handle);
  22. char*       ToCstr (char*);
  23. char*       ToPstr (char*);
  24.  
  25. I've modified GetParamCount to take minimum, maximum; and CheckParamCount
  26. to take a required amount.  They no longer take a "string" error msg.
  27. Instead, they return either the valid paramCount, or they return -1.
  28. The main program calls Fail with the appropriate error message.  This
  29. makes the xxxParamCount routines independent of the main program.
  30.  
  31. XCmdStrings.c contains many of the string-functions that normally come
  32. from the ANSII Library.  But since the library is so large, I've written
  33. these string-functions here to reduce the size of the final XCMD code.
  34.  
  35. In THINK-C, you would open the XCmdGlue.π project.  Then you should
  36. use "Set Project Type" under the Project menu to setup the XCMD info.
  37. The enclosed example defines the following information:
  38.  
  39.   X Code Resource
  40.   File Type:  XCMD
  41.   Creator:    RlGq
  42.   Name:  Dialog
  43.   Type:  XCMD
  44.   ID:    5901
  45.  
  46. Once you've done "Bring Up To Date", you can "Build Code Resource".
  47. Then Quit from THINK-C and use ResEdit to Copy the XCMD resource
  48. from the XCmdDialog file and Paste it into a HyperCard stack.
  49. I've supplied a HyperCard 2.0 stack called XCmdStack that already
  50. has this XCMD in place (along with a couple of others).  There is
  51. also a card-script (shown below) that gives Dialog a workout.
  52. Just bring up the Message Box (command-M), and type:  tryit
  53.  
  54. On tryit
  55.   Dialog
  56.   get the result
  57.   if it is not empty then put it into the message box
  58.   Dialog "Play it again Sam?", 100, 80, "Geneva"
  59. End tryit
  60.  
  61. Notice that XCmdUtil makes it simpler to code the examples in Chapter 6
  62. because most of the commonly used routines are included in XCmdUtil.
  63. Something like NewMenuBar would #include "XCmdUtil.h" and only define
  64. the prototype for: pascal void main (XCmdBlockPtr);  and you'd replace
  65. the CheckParamCount call as follows:
  66.  
  67.   if (CheckParamCount(paramPtr,requiredParamCount) < 0)
  68.   {  Fail(paramPtr, "Form: NewMenuBar \"Your About Name\"");
  69.      return;
  70.   }
  71.  
  72. And you'd only have to code the main routine.  If you make use of any of
  73. the string-functions, like "strcpy" in the NewMenuBar XCMD, then you must
  74. #include <string.h> to guarantee the proper prototypes are defined.  That
  75. is true of any of the examples in Chapter 6.  Not all string-functions
  76. have been defined in XCmdStrings, so take a look at XCmdStrings.c before
  77. using string-functions.  If they aren't there, you may have to add them.
  78. And note that XCmdUtil.c needs XCmdStrings.c, so be sure to have both of
  79. them in your project window, or use the standard ANSII library in place
  80. of the XCmdStrings.c module.  It's up to you.
  81.  
  82. Lastly, pay particular attention to the Hints and Tips at the end of
  83. Chapter 2.  The ID-numbers of Code Resources must not conflict, and you
  84. must "Name" them with names that don't conflict with HyperCard reserved
  85. words.  Use "Set Project Type" to make changes for other XCMDs.  You just
  86. replace the XCmdDialog.c module in the XCmdGlue.π project, and make a new
  87. XCMD file (Note that XCmdGlue.π.rsrc defines the XCMD icon).
  88.  
  89. Have fun!
  90.